Repository navigation
feat(docs): docs MCP at cloudhal.dev/mcp and Accept: text/markdown (RFC-0037 phase 3) - #37
Merged
Merged
Conversation
…FC-0037 phase 3) The cloudhal-dev Worker gets a small script in front of the assets: - /mcp: a standalone, read-only, unauthenticated docs MCP (Streamable HTTP, stateless, JSON answers) with search_docs and read_doc, rate limited to 100 requests a minute per IP (MCP_RATE_LIMITER); - Accept: text/markdown on a page answers its .md copy with Vary: Accept and x-markdown-tokens; everything else goes to the assets binding unchanged. postbuild.ts writes the search index from the same page list as the HTML, the .md copies and llms.txt; the Worker ranks with BM25 and prefix matches. Sections move to src/lib/sections.ts. ADR-0039 rule 4 and RFC-0037 §4 are amended: the site MCP server (cloudhal mcp, remote /mcp) gets no docs tools. It serves agents working on sites, its how-to knowledge lives in skills, tool descriptions and server instructions, and docs tools would add irrelevant tools for narrow keys, a second knowledge source and an outbound dependency. Its instructions now only name https://cloudhal.dev/llms.txt. docs/agents/docs-for-agents.md explains how to add the docs MCP to Claude Code, Codex, Cursor, VS Code and Claude Desktop. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
Merged
5 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds on #36 (merged).
What
https://cloudhal.dev/mcp: a standalone, read-only, unauthenticated docs MCP in thecloudhal-devWorker (apps/docs/src/worker). Streamable HTTP, stateless (no session id, no SSE; GET/DELETE → 405), protocol versions 2024-11-05 … 2025-11-25.search_docs({ query, section? })→ up to 8{ title, url, snippet }(also asstructuredContentwith anoutputSchema);read_doc({ url })→ the page's Markdown; only cloudhal.dev URLs or site paths.ratelimitsbindingMCP_RATE_LIMITER, 429 +Retry-After).scripts/postbuild.tsfrom the same page list (src/lib/pages.ts) →/_mcp/search-index.json(~2.2 MB, loaded once per isolate). BM25 with title/description/path boosts and prefix matches; snippets centre on the densest cluster of query words.Accept: text/markdownon any page answers its.mdcopy withVary: Acceptandx-markdown-tokens; page HTML getsVary: Accept; everything else goes to the assets binding unchanged (run_worker_first: true).cloudhal mcp/ remote/mcp). Reasons are recorded there. The site server's instructions get one line naminghttps://cloudhal.dev/llms.txt(changeset:@cloudhal/mcp-serverpatch).docs/agents/docs-for-agents.md: how to add the docs MCP to Claude Code, Codex, Cursor, VS Code and Claude Desktop (no auth), and why it is separate from the site MCP.Checks
pnpm --filter @cloudhal/docs test(33, incl. newtest/worker.test.ts, no network),typecheck,buildpnpm --filter @cloudhal/mcp-server test(140)biome check,size:checkwrangler dev: initialize,notifications/initialized→ 202, tools/list, search_docs, read_doc, GET → 405, Markdown negotiation headers; plus the official@modelcontextprotocol/client(Streamable HTTP transport) connecting, listing, searching and reading.Not deployed. Before the first deploy, check that
wrangler deployaccepts theratelimitsnamespace id1039on the account.🤖 Generated with Claude Code